Best Tools for JAVA

home *** CD-ROM | disk | FTP | other *** search

/ Best Tools for JAVA / Best Tools for JAVA.iso / JAVA_ALL / JDBC / JDBC_011 / JAVA / SQL / PREPARED.JAV < prev next >

Wrap

Text File | 1996-11-10 | 12.7 KB | 325 lines

/* * Copyright (c) 1996 Sun Microsystems, Inc. All Rights Reserved. * * Permission to use, copy, modify, and distribute this software * and its documentation for NON-COMMERCIAL purposes and without * fee is hereby granted provided that this copyright notice * appears in all copies. Please refer to the file "LICENSE" * for further important copyright and licensing information. * * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF * THE SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED * TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A * PARTICULAR PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR * ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR * DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES. * * THIS SOFTWARE IS NOT DESIGNED OR INTENDED FOR USE OR RESALE AS ON-LINE * CONTROL EQUIPMENT IN HAZARDOUS ENVIRONMENTS REQUIRING FAIL-SAFE * PERFORMANCE, SUCH AS IN THE OPERATION OF NUCLEAR FACILITIES, AIRCRAFT * NAVIGATION OR COMMUNICATION SYSTEMS, AIR TRAFFIC CONTROL, DIRECT LIFE * SUPPORT MACHINES, OR WEAPONS SYSTEMS, IN WHICH THE FAILURE OF THE * SOFTWARE COULD LEAD DIRECTLY TO DEATH, PERSONAL INJURY, OR SEVERE * PHYSICAL OR ENVIRONMENTAL DAMAGE ("HIGH RISK ACTIVITIES"). SUN * SPECIFICALLY DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY OF FITNESS FOR * HIGH RISK ACTIVITIES. */ package java.sql; /** * A SQL statement is pre-compiled and stored in a * PreparedStatement object. This object can then be used to * efficiently execute this statement multiple times. * * Note: The setXXX methods for setting IN parameter values * must specify types that are compatible with the defined SQL type of * the input parameter. For instance, if the IN parameter has SQL type * Integer then setInt should be used. * * If arbitrary parameter type conversions are required then the * setObject method should be used with a target SQL type. * * @see Connection#prepareStatement * @see ResultSet */ public interface PreparedStatement extends Statement { /** * A prepared SQL query is executed and its ResultSet is returned. * * @return a ResultSet that contains the data produced by the * query; never null */ ResultSet executeQuery() throws SQLException; /** * Execute a SQL INSERT, UPDATE or DELETE statement. In addition, * SQL statements that return nothing such as SQL DDL statements * can be executed. * * @return either the row count for INSERT, UPDATE or DELETE; or 0 * for SQL statements that return nothing */ int executeUpdate() throws SQLException; /** * Set a parameter to SQL NULL. * * Note: You must specify the parameter's SQL type. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param sqlType SQL type code defined by java.sql.Types */ void setNull(int parameterIndex, int sqlType) throws SQLException; /** * Set a parameter to a Java boolean value. The driver converts this * to a SQL BIT value when it sends it to the database. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the parameter value */ void setBoolean(int parameterIndex, boolean x) throws SQLException; /** * Set a parameter to a Java byte value. The driver converts this * to a SQL TINYINT value when it sends it to the database. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the parameter value */ void setByte(int parameterIndex, byte x) throws SQLException; /** * Set a parameter to a Java short value. The driver converts this * to a SQL SMALLINT value when it sends it to the database. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the parameter value */ void setShort(int parameterIndex, short x) throws SQLException; /** * Set a parameter to a Java int value. The driver converts this * to a SQL INTEGER value when it sends it to the database. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the parameter value */ void setInt(int parameterIndex, int x) throws SQLException; /** * Set a parameter to a Java long value. The driver converts this * to a SQL BIGINT value when it sends it to the database. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the parameter value */ void setLong(int parameterIndex, long x) throws SQLException; /** * Set a parameter to a Java float value. The driver converts this * to a SQL FLOAT value when it sends it to the database. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the parameter value */ void setFloat(int parameterIndex, float x) throws SQLException; /** * Set a parameter to a Java double value. The driver converts this * to a SQL DOUBLE value when it sends it to the database. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the parameter value */ void setDouble(int parameterIndex, double x) throws SQLException; /** * Set a parameter to a java.lang.Bignum value. The driver converts this * to a SQL NUMERIC value when it sends it to the database. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the parameter value */ void setBignum(int parameterIndex, Bignum x) throws SQLException; /** * Set a parameter to a Java String value. The driver converts this * to a SQL VARCHAR or LONGVARCHAR value (depending on the arguments * size relative to the driver's limits on VARCHARs) when it sends * it to the database. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the parameter value */ void setString(int parameterIndex, String x) throws SQLException; /** * Set a parameter to a Java array of bytes. The driver converts * this to a SQL VARBINARY or LONGVARBINARY (depending on the * argument's size relative to the driver's limits on VARBINARYs) * when it sends it to the database. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the parameter value */ void setBytes(int parameterIndex, byte x[]) throws SQLException; /** * Set a parameter to a java.sql.Date value. The driver converts this * to a SQL DATE value when it sends it to the database. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the parameter value */ void setDate(int parameterIndex, java.sql.Date x) throws SQLException; /** * Set a parameter to a java.sql.Time value. The driver converts this * to a SQL TIME value when it sends it to the database. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the parameter value */ void setTime(int parameterIndex, java.sql.Time x) throws SQLException; /** * Set a parameter to a java.sql.Timestamp value. The driver * converts this to a SQL TIMESTAMP value when it sends it to the * database. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the parameter value */ void setTimestamp(int parameterIndex, java.sql.Timestamp x) throws SQLException; /** * When a very large ASCII value is input to a LONGVARCHAR * parameter, it may be more practical to send it via a * java.io.InputStream. JDBC will read the data from the stream * as needed, until it reaches end-of-file. The JDBC driver will * do any necessary conversion from ASCII to the database char format. * * Note: This stream object can either be a standard * Java stream object or your own subclass that implements the * standard interface. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the java input stream which contains the ASCII parameter value * @param length the number of bytes in the stream */ void setAsciiStream(int parameterIndex, java.io.InputStream x, int length) throws SQLException; /** * When a very large UNICODE value is input to a LONGVARCHAR * parameter, it may be more practical to send it via a * java.io.InputStream. JDBC will read the data from the stream * as needed, until it reaches end-of-file. The JDBC driver will * do any necessary conversion from UNICODE to the database char format. * * Note: This stream object can either be a standard * Java stream object or your own subclass that implements the * standard interface. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the java input stream which contains the * UNICODE parameter value * @param length the number of bytes in the stream */ void setUnicodeStream(int parameterIndex, java.io.InputStream x, int length) throws SQLException; /** * When a very large binary value is input to a LONGVARBINARY * parameter, it may be more practical to send it via a * java.io.InputStream. JDBC will read the data from the stream * as needed, until it reaches end-of-file. * * Note: This stream object can either be a standard * Java stream object or your own subclass that implements the * standard interface. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the java input stream which contains the binary parameter value * @param length the number of bytes in the stream */ void setBinaryStream(int parameterIndex, java.io.InputStream x, int length) throws SQLException; /** * In general, parameter values remain in force for repeated use of a * Statement. Setting a parameter value automatically clears its * previous value. However, in some cases it is useful to immediately * release the resources used by the current parameter values; this can * be done by calling clearParameters. */ void clearParameters() throws SQLException; //---------------------------------------------------------------------- // Advanced features: /** * Set the value of a parameter using an object; use the * java.lang equivalent objects for integral values. * * The given Java object will be converted to the targetSqlType * before being sent to the database. * * Note that this method may be used to pass datatabase- * specific abstract data types. This is done by using a Driver- * specific Java type and using a targetSqlType of * java.sql.types.OTHER. * * @param parameterIndex The first parameter is 1, the second is 2, ... * @param x The object containing the input parameter value * @param targetSqlType The SQL type (as defined in java.sql.Types) to be * sent to the database. The scale argument may further qualify this type. * @param scale For java.sql.Types.DECIMAL or java.sql.Types.NUMERIC types * this is the number of digits after the decimal. For all other * types this value will be ignored, * @see Types */ void setObject(int parameterIndex, Object x, int targetSqlType, int scale) throws SQLException; /** * This method is like setObject above, but assumes a scale of zero. */ void setObject(int parameterIndex, Object x, int targetSqlType) throws SQLException; /** * Set the value of a parameter using an object; use the * java.lang equivalent objects for integral values. * * The JDBC specification specifies a standard mapping from * Java Object types to SQL types. The given argument java object * will be converted to the corresponding SQL type before being * sent to the database. * * Note that this method may be used to pass datatabase * specific abstract data types, by using a Driver specific Java * type. * * @param parameterIndex The first parameter is 1, the second is 2, ... * @param x The object containing the input parameter value */ void setObject(int parameterIndex, Object x) throws SQLException; /** * Some prepared statements return multiple results; the execute * method handles these complex statements as well as the simpler * form of statements handled by executeQuery and executeUpdate. * * @see Statement#execute */ boolean execute() throws SQLException; }